Skip to main content

API Reference

REST Endpoints​

Message Operations​

Send Message (REST Fallback)​

POST /api/message

Headers:

  • Authorization: Bearer token
  • authid: Authentication ID
  • sid: Session ID

Request Body:

{
  "recipient_id": 123,        // User ID of recipient
  "recipient_oid": 456,       // Optional: Organization ID of recipient
  "sender_oid": 789,         // Optional: Organization ID of sender
  "message": "Hello!",
  "entity_id": 101,          // Optional: Related entity ID
  "attachment": {            // Optional: Attachment details
    "file_name": "doc.pdf",
    "file_url": "https://..."
  },
  "priority": "normal"       // Optional: Message priority
}

Response:

{
  "status": 200,
  "data": {
    "message_id": "60c...",
    "timestamp": 1623456789,
    "status": "sent"
  }
}

Get Message History​

GET /api/messages/history

Query Parameters:

  • recipient_id: (optional) Recipient user ID
  • sender_id: (optional) Sender user ID
  • recipient_oid: (optional) Recipient organization ID
  • sender_oid: (optional) Sender organization ID
  • entity_id: (optional) Entity ID
  • page: Page number (default: 1)
  • page_size: Messages per page (default: 10)
  • timestamp_marker: (optional) UNIX timestamp

Response:

{
  "status": 200,
  "data": {
    "total_count": 50,
    "page": 1,
    "page_size": 10,
    "messages": [...]
  }
}

Get Message Summary​

GET /api/messages/summary

Query Parameters: Similar to message history endpoint

Response:

{
  "status": 200,
  "data": {
    "total_unread": 5,
    "total_undelivered": 2,
    "conversation_summaries": [...]
  }
}

Get Unique Conversations​

GET /api/messages/conversations

Query Parameters:

  • id: User ID, or
  • oid: Organization ID

Response:

{
  "status": 200,
  "data": {
    "total_conversations": 10,
    "conversations": [...]
  }
}

Get Conversations with Perspective​

GET /api/messages/conversations/perspective

Query Parameters:

  • id: User ID, or
  • oid: Organization ID
  • perspective: "sender" or "receiver"

Response: Same as conversations endpoint

Mark Messages as Read​

PUT /api/message/read

Request Body:

{
  "identifiers": [
    "60c...",  // MongoDB ObjectId
    "hash123"  // Message hash
  ]
}

Delete Message​

DELETE /api/message/delete

Request Body:

{
  "message_id": "60c..."
}

Error Responses​

All endpoints may return the following error responses:

{
  "status": 400,
  "data": {
    "error": "Error description"
  }
}

Common status codes:

  • 400: Bad Request
  • 401: Unauthorized
  • 403: Forbidden
  • 404: Not Found
  • 429: Too Many Requests
  • 500: Internal Server Error

Rate Limiting​

Rate limits are configured via the RATELIMIT_DEFAULT environment variable:

RATELIMIT_DEFAULT=200 per day;50 per hour

When rate limit is exceeded:

{
  "status": 429,
  "data": {
    "error": "Rate limit exceeded",
    "retry_after": 3600
  }
}

Authentication​

All endpoints require authentication headers:

Authorization: Bearer <jwt_token>
authid: <auth_id>
sid: <session_id>

Invalid or missing authentication will result in:

{
  "status": 401,
  "data": {
    "error": "Invalid authentication credentials"
  }
}